Collapse WORKFLOW.md 5A to a Procedure and an Evidence Rule - #1394
Conversation
5A carried nine "Core" bullets restating section 4's D-guarantees and five per-type addenda, roughly 2400 words of a second hand-authored wording of the contract. It is now three paragraphs: how a verdict is recorded, where evidence lives when it is not in the workflow files, and how to cite it. A section that says where to look cannot disagree with the section that says what must hold, so 32 of the 44 findings on the section 5 tracker are unwritable rather than fixed: each quotes 5A text that no longer exists. Section 4 keeps the requirement, together with whatever each guarantee defers to. Also fixed, from the pre-existing backlog #1393 opened: - S1 and S4 gave one job two conclusions in one cell. D2.2 makes the check exit early while the job succeeds, which is what the cells now say. - S11 stated merge-bot auto-merge as the required output, contradicting D8.3's `auto-merge: false` tracker, which prefixes the head so no rule matches. - 5C's maintainer-only fence reached only a probe that dispatches or re-runs, so its first bullet told an agent to open a pull request on the repo it audits. - The Assessment restated 5A's recording rule more narrowly than 5A states it, and spelled the N/A token two ways. Swept to match: section 1's applicability rule and its two-layer bullet, section 6's three references to the deleted addenda, `AUDIT.md` section 5, and the `audit-a-repo` and `workflow-ci-contract` skills. Two requirements had no home outside 5A and are filed rather than moved, since each needs a decision about which guarantee should own it: the `pypi` environment's deployment-branch rule, which #1370 item 43 shows would block every `.dev0` develop publish D3.4 requires, and the static-site generator's pin-by-version-and-checksum. Refs #1370, #1393, #1311 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…amble The preamble read "Which of its checks and scenarios bind a given repository", which went stale when 5A stopped carrying checks. Calling them guarantees instead made the sentence circular, since section 5 holds no guarantees and the same sentence locates the D-guarantees in section 4. It now names each half by where it lives, 5A's items and 5B's scenarios, so neither noun claims section 5 owns guarantees and the 5A half of applicability is no longer dropped. "Exercises" is the scenario table's own column word, where "trace" takes the scenario as its object everywhere else in the section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Six defects the whole-unit passes found in this change's own text. S11 named the bump PR's head as `<prefix>-<branch>` before its fork, so the claim was asserted on both legs, and D8.3 says an `auto-merge: false` tracker prefixes the head so no merge-bot rule matches it. The cell now names the PR without the prefix. Its expected output also restated D8.3's matching obligation, which is the second home this change exists to remove, so the cell states the two outcomes and cites the guarantee for the rule. 5A's citation forms were narrower than the evidence list two lines above them. A composite action reached at the caller's pin lives in another repository, so a bare `file:line` is wrong for it, and this fleet counts a secret name as its own kind of evidence rather than as a repository setting. Both are covered now. The evidence sentence also claimed every guarantee whose evidence lies outside the workflow files names where, which D8.2 falsifies by naming no location for `.github/dependabot.yml`. The skill's applicability bullet qualified a 5B scenario as "tracing one" guarantee, where S7 exercises five, and the qualifier invited tying a scenario's applicability to its guarantee's, which section 5's own S9 rule contradicts. The carried test-methodology preamble enumerated what section 5 holds in three successive wordings that were stale, circular, and self-referential in turn. It now names the section below as the subject and says its items and scenarios answer to section 4's D-guarantees. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…Term Section 1's applicability rule no longer names a 5A check, and three surfaces still cited it for that word: AUDIT.md's gate, its own flowchart node, and the audit-a-repo skill. Each now says "an item or check", marked as this audit's extension of section 1 rather than as section 1's own text, since AUDIT.md grades spec checks that section 1 says nothing about. The audit-a-repo skill had tracked only half of AUDIT.md section 5's rule, the citation form, and not the instruction to read a called workflow at the SHA the caller pins. Without it the skill's own "read main as ground truth" was the nearest branch rule, so an auditor would trace a job graph through the hub's current main rather than the commit the audited repo runs. The source-only walkthrough briefly recorded D4.6 and D5.6 N/A. Blog declares ["hugo", "source-only"], so that negated the static-site bullet for a live repo and would have dropped the live-host assertion and the retention-ownership check its committed report grades as passing. Its N/A list is now item-level, D5.1-D5.5 and D6.1 and D6.3 rather than "D5/D6 artifact items", and names the five build targets, so neither class can be read to cover the deploy surface. Refs #1370, #1393, #1311 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Team Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
🟢 Approval recommended
The edits consistently collapse 5A to procedure/evidence rules and the sweeps keep AUDIT.md and skill distributions aligned without introducing internal inconsistencies.
Pull request overview
This pull request collapses WORKFLOW.md section 5A from a large restated rule set into a concise procedure/evidence rule, then sweeps the audit procedure and the workflow-ci-contract/audit-a-repo skill surfaces to match.
Changes:
- Rewrite
WORKFLOW.md5A to describe how to record/cite audit evidence rather than restating section 4 guarantees. - Update trace scenarios and probe wording to remove contradictory job-level “skipped (smoke), succeeds” language and clarify maintainer-only probes.
- Sweep
AUDIT.md, skill copies, and the canonical review ledger to reflect the new 5A shape and applicability phrasing.
File summaries
| File | Description |
|---|---|
| WORKFLOW.md | Collapses 5A to an audit procedure + evidence rule; updates scenarios/probe text to match. |
| AUDIT.md | Aligns applicability language and updates the “assert Actions implement WORKFLOW.md” step to cite pinned-call evidence. |
| reports/canonical-review.json | Records updated whole-unit review stamps/digests for touched canonical units. |
| .agents/skills/workflow-ci-contract/SKILL.md | Updates applicability/two-layer wording to reflect removal of “5A checks” as a separate surface. |
| .agents/skills/workflow-ci-contract/references/test-methodology.md | Regenerates the included section 5 text with the collapsed 5A procedure/evidence rule. |
| .agents/skills/audit-a-repo/SKILL.md | Updates measuring guidance to apply applicability to AUDIT.md checks and to read pinned-called workflows at their SHA. |
| .github/skills/workflow-ci-contract/SKILL.md | Generated copy of the workflow-ci-contract skill updated to match source. |
| .github/skills/workflow-ci-contract/references/test-methodology.md | Generated copy of the included methodology updated to match source. |
| .github/skills/audit-a-repo/SKILL.md | Generated copy of the audit-a-repo skill updated to match source. |
| .claude-plugin/fleet-skills/skills/workflow-ci-contract/SKILL.md | Generated plugin skill copy updated to match source. |
| .claude-plugin/fleet-skills/skills/workflow-ci-contract/references/test-methodology.md | Generated plugin include copy updated to match source. |
| .claude-plugin/fleet-skills/skills/audit-a-repo/SKILL.md | Generated plugin skill copy updated to match source. |
| .claude-plugin/fleet-skills/.source-digests/workflow-ci-contract | Updates source digest for the generated plugin workflow-ci-contract unit. |
| .claude-plugin/fleet-skills/.source-digests/audit-a-repo | Updates source digest for the generated plugin audit-a-repo unit. |
Review details
- Files reviewed: 14/14 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…e YAML Conventions (#1395) Collapses pull requests 2, 4 and 6 of the #1311 sequence into one change, which the maintainer agreed to because the three touch the same surfaces and, run sequentially, each would re-sweep what the last swept and pay the seam cost three times. ## What it does **#1206's two maintainer decisions, applied first**, since sections 4 and 6 and `GOVERNANCE.md` all depend on them. D9 binds exactly as D1 through D8 do, so a style violation is a defect and `GOVERNANCE.md`'s target-state framing settles *when* an unswept workflow is fixed rather than *whether* the violation counts. An overlap resolves **by subject** rather than by blanket precedence, and every section 1 to 6 now has a named owner. **Section 4's two longest items shrink to their outcomes**, D1.6 from about 974 words and D4.5 from about 602. Nothing is deleted: the Microsoft.Testing.Platform runner, package floor and its silently-green failure modes move to `dotnet-codestyle`, the `pytest-cov` dependency and coverage selector to `python-codestyle`, and the failed-push recovery routes to `operational-vs-release-workflow`. **Section 6 states only what each type adds, and carries no N/A list at all.** All eight per-type N/A lists are deleted rather than corrected, because such a list is right for a single-type repository and negates a construct a second declared type supplies, which is the defect #1394 shipped through fifteen clean unit passes. Section 1's applicability rule derives the N/A set instead, so no row can take away what another row gives. Rows are added for the seven registry types that had none, `upstream-wrapper` is split out of `docker`, and the construct table keys on the construct being present rather than on a registry field. **`GOVERNANCE.md` "Workflow YAML Conventions" is swept** for the items on #1367. ## What is deliberately not done - **D6.2's publisher exception stays withdrawn.** A fourth wording was attempted here and disproved by `get-version-task.yml`, a called workflow whose branch classification comes from the caller's `GITHUB_REF` exactly as D3.1 requires. The item returns to the text `develop` carries and #1369 records all four disproofs. - **No bullet-to-D-item mapping.** One was added here, proved wrong four ways, drifted between its two copies in the round that wrote it, and was deleted on the maintainer's call. - **No per-guarantee evidence map**, per the decision recorded on #1311 step 16. - **The `pypi` environment's deployment-branch rule is not restored**, per the caveat #1370 records: its one plausible content would block every `.dev0` publish D3.4 requires. ## Review evidence 21 read-only passes on the strongest tier before this pull request existed: 11 in round one (10 whole-unit carried-content plus a cross-unit diff pass briefed to hold `registry/repos.json` open), 9 in round two, and a terminal pair scoped to false claims and unfollowable instructions. Roughly 220 findings, the large majority introduced by this change and disposed of in it. The terminal pass over `GOVERNANCE.md`, `AUDIT.md`, `CODESTYLE.md` and the four skills returned zero. The measurement worth recording: **the deletions were right first time and the reasons drew nearly everything.** Five claims about GitHub Actions behaviour that this change introduced were falsified by the tree and reverted, among them that `always()` and `!failure() && !cancelled()` are interchangeable-with-a-preference (D1.5 *requires* `always()` for the aggregator), and that the registry's `releaseTrigger` decides publish-scenario applicability (it says `two-phase` for this repository while `publish-release.yml` is `workflow_dispatch:` only). A carried-content pass is recorded for all 23 canonical units this change moves. ## Owed on merge `spec/files.json` declares both edited `GOVERNANCE.md` sections at `verbatim` fidelity, so every downstream copy goes stale and a fleet resync follows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…sh the WORKFLOW.md Reshape (#1397) Closes #1205. Closes #1212. Closes #1240. Closes #1250. Closes #1267. Closes #1268. Closes #1271. Closes #1288. Closes #1305. Closes #1314. Sixteen commits, ten issues. Each was driven as its own feature pull request into `develop`, reviewed by the PR-hosted reviewers, and merged only with CI green and every finding disposed of by one of the five outcomes: fixed, declined on evidence, decided by the maintainer, deferred behind a filed issue, or fixed as a class. ## What this promotes **The one-home include mechanism and its first six classes** (#1317). `scripts/build_dist.py` gained include regions filled from a rule's home and checked by `--check` (#1378), so a Skill carries a rule's whole text without a copy that can drift. Classes 2 to 6 then converted the restatements: `agent-conduct`'s three conduct sections (#1382), `pr-review-conduct`'s five outcomes into `drive-pr` with every step-ref renamed to a heading (#1383), `backlog-burndown`'s two narrowing rows cut to the narrowing with fourteen restatements pointered (#1384), `WORKFLOW.md` section 4 into `workflow-ci-contract` (#1385), and section 2 cut to a pointer at `GOVERNANCE.md` "Workflow YAML Conventions" (#1388). **The `WORKFLOW.md` reshape** (#1311 step 14's six-pull-request sequence, now finished). The verdict clause aligned with section 5's Assessment (#1390), sections 3 and 5 carried into `workflow-ci-contract` as generated includes (#1392), 5A collapsed to a procedure and an evidence rule (#1394), and the preamble decisions settled alongside the reshape of section 4, section 6 and the YAML conventions (#1395). Section 4's two longest items shrank to their outcomes with the displaced knowledge moved rather than deleted, and section 6 now states only what each type adds, carrying no N/A list at all. **The review loop's stop rule and disposition policy** (#1330), rewriting disposal by deletion and committing the condition under which a whole-unit loop ends, which #1267 filed as missing. **The Merge Gate's bound on an out-of-diff prose finding**, with the reviewer footing recorded (#1333), and reviewer bots scoped away from the generated Skill mirrors (#1329) so a mirror's diff is never reviewed in place of its source. **The fleet label set**, declared and applied through `configure.sh` (#1334). **The review ledger and skills digest decoupled from the working tree** (#1328), so concurrent branches no longer conflict in a generated report that cannot be hand-merged. Plus one grouped Dependabot bump, `docker/setup-qemu-action` 4.2.0 to 4.3.0 (#1325). ## What is deliberately not closed `#1311`, `#1317`, `#1206`, `#1367`, `#1369`, `#1370`, `#1371`, `#1386` and `#1237` each still hold findings this work did not settle. #1317 stands at class 6 of fourteen, and #1311's step 17 comment records what the reshape filed rather than fixed. ## Owed on merge `spec/files.json` declares both edited `GOVERNANCE.md` sections at `verbatim` fidelity, so every downstream copy goes stale on this promotion and a fleet resync follows it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Pull request 3 of the #1311 reshape sequence, and the third to ship after PR 1 (#1373) and PR 5 (#1392).
What it does
WORKFLOW.md5A carried nine "Core" bullets restating section 4's D-guarantees and five per-type addenda, roughly 2400 words of a second hand-authored wording of the contract. It is now three paragraphs: how a verdict is recorded, where evidence lives when it is not in the workflow files, and how to cite it. Section 5 drops from about 3000 words to 1000.A section that says where to look cannot disagree with the section that says what must hold, so 32 of #1370's 44 findings are unwritable rather than fixed: each quotes 5A text that no longer exists. The two finding classes step 14 measured, "5A contradicts or misstates the guarantee it audits" (15 items) and "unsupported check" (8 items), have no surface left to sit on.
Also fixed, from #1393
WORKFLOW.md > 5. Test Methodology#1370 items 2 and 44). S1 and S4 read "validate-release skipped (smoke), succeeds", one job with two conclusions. D2.2 makes the check exit early while the job succeeds, and warns against reading that as a job-level skip, which the old wording invited.auto-merge: falsetracker, which prefixes the head so no merge-bot rule matches.WORKFLOW.md > 5. Test Methodology#1370 item 31). 5C's maintainer-only fence reached only a probe that dispatches or re-runs, so its first bullet told an agent to open a pull request on the repository it audits.Swept to match: section 1's applicability rule and its two-layer bullet, section 6's three references to the deleted addenda,
AUDIT.mdsections 3 and 5 plus its flowchart node, and theaudit-a-repoandworkflow-ci-contractskills.Review
Sixteen whole-unit carried-content passes over ten units and five diff passes, all on the strongest tier, before this pull request existed. They raised roughly 70 findings. Every one was on this change's own text or on a surface this change put in disagreement; none was against the collapse itself. All ten changed canonical units carry a recorded pass at their current text, and the local review receipt covers the final content.
The maintainer settled one design question mid-flight: an interim revision carried a per-guarantee evidence map, and it was deleted because a per-guarantee map is itself a hand-authored second surface and regenerated the same defect class it replaced, at smaller scale. That decision is what the current three-paragraph shape implements.
Known and filed, not fixed here
docs/reusable-workflows.mdreadsgithub.ref_namein four places. Moving the carve-out into D6.2 was attempted twice and withdrawn twice, each time on verified evidence that the wording was wrong. Section 4 is pull request 2's, and the evidence is filed for it.AUDIT.mdandaudit-a-reponow tell an auditor to read a called workflow at the SHA the caller pins, and 5A's citation rule admits that evidence, but 5B, where the job graph is actually walked, does not say it.pypienvironment's deployment-branch rule, which Tracker:WORKFLOW.md > 5. Test Methodology#1370 item 43 shows would block every.dev0develop publish D3.4 requires, is genuinely lost. The static-site generator's checksum pin survives asspec/project-types.json'shugo.generator.pinned.Full disposition, including the section 6 and
AUDIT.mditems this review surfaced, is on #1370.Refs #1311, #1370, #1393
🤖 Generated with Claude Code